## 服务号

### 创建服务号

```sh
curl -X POST \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{appkey}}" \
  -H "Content-Type: application/json" \
  -d '{"name":"My First Service-conversation"}' \
  https://{{host}}/1.2/rtm/service-conversations
```

对话的字段可参考即时通讯总览里面的 [对话](realtime_v2.html#对话（Conversation）)。

返回
```
{"objectId"=>"5a5d7432c3422b31ed845e75", "createdAt"=>"2018-01-16T03:40:32.814Z"}
```

### 查询服务号

```sh
curl -X GET \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{appkey}}" \
  -G \
  --data-urlencode 'where={"name": "service"}' \
  --data-urlencode 'skip=1' \
  --data-urlencode 'limit=20' \
  https://{{host}}/1.2/rtm/service-conversations
```

参数 | 约束 | 说明
---|---|---
skip | 可选 |
limit | 可选 | 与 skip 联合使用实现分页
where | 可选 | 参考 [数据存储 - 查询](rest_api.html#查询)。


返回
```
{"results"=>[{"name"=>"My First Service-conversation", "createdAt"=>"2018-01-17T04:15:33.386Z", "updatedAt"=>"2018-01-17T04:15:33.386Z", "objectId"=>"5a5ecde6c3422b738c8779d7"}]}
```

### 更新服务号

```sh
curl -X PUT \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{appkey}}" \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated Service-conversation"}' \
  https://{{host}}/1.2/rtm/service-conversations/{conv_id}
```

返回
```
{"updatedAt"=>"2018-01-16T03:40:37.683Z", "objectId"=>"5a5d7433c3422b31ed845e76"}
```


### 删除服务号

```sh
curl -X DELETE \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{appkey}}" \
  https://{{host}}/1.2/rtm/service-conversations/{conv_id}
```

返回
```
{}
```

### 订阅服务号

```sh
curl -X POST \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"client_id"}' \
  https://{{host}}/1.2/rtm/service-conversations/{conv_id}/subscribers
```

返回
```
{}
```

### 取消订阅

```sh
curl -X DELETE \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  https://{{host}}/1.2/rtm/service-conversations/{conv_id}/subscribers/{client_id}
```

返回
```
{}
```

### 遍历查询订阅者

该接口要求使用 master key。
```sh
curl -X GET \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  https://{{host}}/1.2/rtm/service-conversations/{conv_id}/subscribers
```

参数 | 约束 | 说明
---|---|---
limit | 可选 | 返回条数限制，默认是 50 条，最大 50 条。
client_id | 可选 | 查询起始订阅者 client id，不填则从订阅者列表起始位置开始遍历。查询结果不会再包含当前指定的订阅者 client id。

返回

```
[{"timestamp":1491467841116,"subscriber":"client id 1","conv_id":"55b871"},
 {"timestamp":1491467852768,"subscriber":"client id 2","conv_id":"55b872"}, ...]
```
其中 timestamp 表示用户订阅系统对话的时间，subscriber 是订阅用户的 client id。如果一次没有获取完，需要从结果列表中取最后一个订阅者的 client id，作为 client_id 参数再次调用本接口以获取下一批订阅者列表。


### 查询订阅者数

该接口要求使用 master key。
```sh
curl -X GET \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  https://{{host}}/1.2/rtm/service-conversations/{conv_id}/subscribers/count
```

返回

```
{"count": 100}
```

### 给所有订阅者发消息

该接口要求使用 master key。
```sh
curl -X POST \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -H "Content-Type: application/json" \
  -d '{"from_client": "", "message": ""}' \
  https://{{host}}/1.2/rtm/service-conversations/{conv_id}/broadcasts
```

参数 | 约束 | 说明
---|---|---
from_client | 必选 | 消息的发件人 client ID
message | 必选 | 消息体
push | 可选 | 附带的推送内容，如果设置，所有 iOS 和 Windows Phone 用户会收到这条推送通知。字符串或 JSON 对象

返回：
```
{"msg-id":"qNkRkFWOeSqP65S9fDyHJw", "timestamp":1495431811151}
```

频率限制：

此接口受频率限制，[点击查看详情](#接口请求频率限制)。

### 修改给所有订阅者发送的消息

该接口要求使用 master key。
从 Objective-C SDK v6.0.0、Android SDK v4.4.0、JavaScript SDK v3.5.0 开始，我们支持了新的修改与撤回消息功能。修改或撤回消息后，即使已经收到并已缓存在客户端的消息也会被修改或撤回。对于老版本的 SDK，仅能修改或撤回服务器端的消息记录，并不能修改或撤回客户端已缓存的消息记录。

```sh
curl -X PUT \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -H "Content-Type: application/json" \
  -d '{"from_client": "", "message": "", "timestamp": 123}' \
  https://{{host}}/1.2/rtm/service-conversations/{conv_id}/messages/{message_id}
```

参数 | 约束 | 说明
---|---|---
from_client | 必填 | 消息的发件人 client ID
message | 必填 | 消息体
timestamp | 必填 | 消息的时间戳

返回：
```
{"result": {}}
```

频率限制：

此接口受频率限制，[点击查看详情](#接口请求频率限制)。

### 撤回给所有订阅者发送的消息

该接口要求使用 master key。需要相应 SDK 的支持，具体可参考上面的「修改给所有订阅者发送的消息」接口。

```sh
curl -X PUT \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -H "Content-Type: application/json" \
  -d '{"from_client": "", "timestamp": 123}' \
  https://{{host}}/1.2/rtm/service-conversations/{conv_id}/messages/{message_id}/recall
```

参数 | 约束 | 说明
---|---|---
from_client | 必填 | 消息的发件人 client ID
timestamp | 必填 | 消息的时间戳

返回：
```
{"result": {}}
```

频率限制：

此接口受频率限制，[点击查看详情](#接口请求频率限制)。

### 给任意用户单独发消息

该接口要求使用 master key。

```sh
curl -X POST \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -H "Content-Type: application/json" \
  -d '{"from_client": "", "message": ""}' \
  https://{{host}}/1.2/rtm/service-conversations/{conv_id}/messages
```
**注意**，由于这个接口的管理性质，当你通过这个接口发送消息时，我们不会检查 **from_client** 是否有权限给这个服务号发送消息，而是统统放行，请谨慎使用这个接口。
如果你在应用中使用了我们内部定义的 [富媒体消息格式](./realtime_v2.html#消息（Message）)，在发送消息时 **message** 字段需要遵守一定的格式要求，[富媒体消息格式说明](./realtime_rest_api.html#富媒体消息格式说明) 中有详细说明。


参数 | 约束 | 说明
---|---|---
from_client | 必填 |消息的发件人 client Id
to_clients | 必填 | 数组类型，表示接收消息的 client Id 列表，最多能包含 20 个 client Id
message | 必填 | 消息内容（这里的消息内容的本质是字符串，但是我们对字符串内部的格式没有做限定，<br/>理论上开发者可以随意发送任意格式，只要大小不超过 5 KB 限制即可。）
transient | 可选|是否为暂态消息，默认 false
no_sync | 可选|默认情况下消息会被同步给在线的 from_client 用户的客户端，设置为 true 禁用此功能。
push_data | 可选 | 以消息附件方式设置本条消息的离线推送通知内容。如果目标接收者使用的是 iOS 设备并且当前不在线，我们会按照该参数填写的内容来发离线推送。请参看 [离线推送通知](./realtime-guide-intermediate.html#离线推送通知)
priority | 可选 | 定义消息优先级，可选值为 high、normal、low，分别对应高、中、低三种优先级。该参数大小写不敏感，默认为高优先级 high。本参数仅对暂态消息或聊天室的消息有效，高优先级下在服务端与用户设备的连接拥塞时依然排队。

返回说明：

默认情况下发送消息 API 使用异步的方式，调用后返回消息 id 和接收消息的服务器时间戳，例如 `{"msg-id":"qNkRkFWOeSqP65S9fDyHJw", "timestamp":1495431811151}`。

频率限制：

此接口受频率限制，[点击查看详情](#接口请求频率限制)。

### 修改给用户单独发送的消息

该接口要求使用 master key。
从 Objective-C SDK v6.0.0、Android SDK v4.4.0、JavaScript SDK v3.5.0 开始，我们支持了新的修改与撤回消息功能。修改或撤回消息后，即使已经收到并已缓存在客户端的消息也会被修改或撤回。对于老版本的 SDK，仅能修改或撤回服务器端的消息记录，并不能修改或撤回客户端已缓存的消息记录。

```sh
curl -X PUT \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -H "Content-Type: application/json" \
  -d '{"from_client": "", "message": "", "timestamp": 123, "to_clients":["a","b","c"]}' \
  https://{{host}}/1.2/rtm/service-conversations/{conv_id}/messages/{message_id}
```

参数 | 约束 | 说明
---|---|---
from_client | 必填 | 消息的发件人 client ID
message | 必填 | 消息体
timestamp | 必填 | 消息的时间戳
to_clients | 必填 | 数组类型，表示接收目标消息的 client Id 列表，最多能包含 20 个 client Id

返回：
```
{"result": {}}
```

频率限制：

此接口受频率限制，[点击查看详情](#接口请求频率限制)。

### 撤回给用户单独发送的消息

该接口要求使用 master key。需要相应 SDK 的支持，具体可参考上面的「修改给用户单独发送的消息」接口。

```sh
curl -X PUT \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -H "Content-Type: application/json" \
  -d '{"from_client": "", "timestamp": 123, "to_clients":["a","b","c"]}' \
  https://{{host}}/1.2/rtm/service-conversations/{conv_id}/messages/{message_id}/recall
```

参数 | 约束 | 说明
---|---|---
from_client | 必填 | 消息的发件人 client ID
timestamp | 必填 | 消息的时间戳
to_clients | 必填 | 数组类型，表示接收目标消息的 client Id 列表，最多能包含 20 个 client Id

返回：
```
{"result": {}}
```

频率限制：

此接口受频率限制，[点击查看详情](#接口请求频率限制)。

### 删除给用户单独发送的消息

本接口要求使用 master key，并且只能删除订阅消息或给用户单独发送的消息，无法删除广播消息。广播消息请使用 [删除广播消息](realtime_rest_api_v2.html#hash-1748962119) 来删除。


```sh
curl -X DELETE \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -G \
  --data-urlencode 'from_client=some-client-id' \
  --data-urlencode 'timestamp=123' \
  https://{{host}}/1.2/rtm/service-conversations/{conv_id}/subscribers/{client_id}/messages/{message_id}
```

> NOTE：该接口仅删除服务端的消息，对客户端无影响。

参数 | 约束 | 说明
---|---|---
from_client | 必填 | 消息的发件人 client ID
timestamp | 必填 | 消息的时间戳

返回：
```
{}
```

### 查询服务号给某用户发的消息

该接口要求使用 master key。查询结果包含服务号发送的订阅广播消息也包含单独发送的消息。

```sh
curl -X GET \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -H "Content-Type: application/json" \
  https://{{host}}/1.2/rtm/service-conversations/{conv_id}/subscribers/{client_id}/messages
```

参数和返回值与 [查询历史消息](#查询历史消息) 相同。

### 黑名单

该功能介绍可参考总览里面的 [黑名单](realtime-guide-senior.html#黑名单)。

#### 增加服务号黑名单

该接口要求使用 master key。

加入黑名单的 client 不允许再加入该服务号，如果之前在该服务号中将被移除。每个服务号最多允许添加 10,000 个黑名单。
```sh
curl -X POST \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -H "Content-Type: application/json" \
  -d '{"client_ids": ["client1", "client2"]}' \
  https://{{host}}/1.2/rtm/service-conversations/{conv_id}/blacklists
```

参数 | 说明
--- | ---
client_ids | 要拉黑的 Client ID 列表，数组

返回

```
{}
```

#### 移除服务号黑名单

该接口要求使用 master key。
```sh
curl -X DELETE \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -d '{"client_ids": ["client1", "client2"]}' \
  https://{{host}}/1.2/rtm/service-conversations/{conv_id}/blacklists
```

返回

```
{}
```

#### 查询服务号黑名单

该接口要求使用 master key。
```sh
curl -X GET \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -d '{"client_ids": ["client1", "client2"]}' \
  https://{{host}}/1.2/rtm/service-conversations/{conv_id}/blacklists
```

参数 | 约束 | 说明
---|---|---
limit | 可选 | 与 next 联合使用实现分页，默认 10
next | 可选 | 第一次查询时返回，后面的查询带着这个参数，实现分页查询

返回

```
{"client_ids": ["client1", "client2"]}
```
